/*
 * Constraint.java
 * 
 * Created on 21-Aug-2007, 08:21:03
 *
 * Copyright (C)
 *
 * This program is free software; you can redistribute it and/or modify it under
 * the terms of the GNU General Public License as published by the Free Software
 * Foundation; either version 2 of the License, or (at your option) any later
 * version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
 * Place, Suite 330, Boston, MA 02111-1307 USA
 */

package com.grubby.databean.constraints.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * A marker for constraint annotations. All annotations that are to be used
 * as constraints must have this annotation associated with them.
 * <P> 
 * The following code shows an example of how to apply this annotation to a 
 * constraint definition
 * <P>
 * <code>@Constraint public @interface MyConstraint {}</code>
 * <P>
 * By default a constraint can be applied to a property of any type. Optionally,
 * the type may be restricted. For example to restrict a constraint to numerics
 * only use <code>@Constraint(Constraint.Type.NUMERIC)</code>.
 * <P>
 * Note it is currently left to the constraint validators to determine if 
 * constraints have been applied to a property of a valid type for
 * that constraint. The validators are not required to make use of the type
 * value on the Constraint annotation, but should be consistent with its intent.
 * <P>
 * Note: this code been adapted from an Annotation processing example created by 
 * Anders Holmgren of Sun Microsystems
 * 
 * @author Anders Holmgren, with alterations by A. HARMEL-LAW. 
 * E: andrew.harmel.law@gmail.com
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.ANNOTATION_TYPE})
@Documented()
public @interface Constraint {
    
    /**
     * An enumeration of the different types that a constraint may be applied 
     * to.
     */
    enum Type { 
    
        /**
         * The constraint may be applied to any type of object
         */
        ANY, 
        
        /**
         * The constraint may be applied to any object for which 
         * Object.toString() yields a meaningful result. In practice, it is up
         * to the application to determine what is meaningful.
         */
        STRING, 
        
        /**
         * The constraint may be applied to numeric objects only. This means
         * any subclass of Number or corresponding primitive type.
         */
        NUMERIC, 
        
        /**
         * The constraint may be applied to collections only. Note the
         * constraints apply to some attribute of the collection itself 
         * (e.g. size) and not to the objects in the collection.
         */
        COLLECTION 
    };
    
    /**
     * The type of object the constraint can be applied to. The default is ANY
     * type.
     */
    Type value() default Type.ANY;
    
}
